POST (REST)
(Web Mining)
Synopsis
Sends a POST http request to a REST service as is used in CRUD operations to create a new resource.Description
This operator can send POST requests to REST services. It can deal with returning text (e.g. JSON or XML) as a document, as well as returning binary data as a file.
For submitting data, you can either submit a document input, manually entered JSON or XML via parameter, or form data. In either case, macros within the input will be resolved before it is submitted to the REST service. Alternatively, you can send (small) binary data as the request body instead. Note that this operator is not build for transmitting large binary files, as it loads the full binary data into memory for request retry mechanisms, caching, etc.
By default, if a web service returns an error in the 4xx or 5xx range, this operator will fail. Sometimes however, some requests may be expected to fail, but the process should still continue (and for example return the error in the output document). In those cases, deselect the fail_on_endpoint_error parameter to keep the process going.
Differentiation
DELETE (REST)
Sends a DELETE request to a REST service. This is mostly used to delete a resource.
GET (REST)
Sends a GET request to a REST service. This is mostly used to download a resource.
PATCH (REST)
Sends a PATCH request to a REST service. This is mostly used to update parts of an existing resource.
PUT (REST)
Sends a PUT request to a REST service. This is mostly used to replace an existing resource or place a resource at a specific location.
Input
request (IOObject)The optional input port. Depending on whether json or binary mode is set in the request body, this expects either a document or a file. If json or xml mode is selected, this port does not need an input as long as the request json or request xml parameter is set.
Output
- response (IOObject)
The output port. Depending on whether text or binary mode is set in the response body, this returns a document or a file.
Parameters
- request urlThe REST service URL which the operator should call.
- request body typeWhether the request body to the REST service should be JSON, XML, form data, or binary data. This parameter determines the expected input data of this operator (document or file) and available parameters.
- request jsonOnly visible if json is selected as the request body type AND no input document is passed to the operator. The JSON contained here is then send as the request body to the REST service.
- request xmlOnly visible if xml is selected as the request body type AND no input document is passed to the operator. The XML contained here is then send as the request body to the REST service.
- request formOnly visible if form is selected as the request body type. The entries contained here are then send as a form request to the REST service.
- response body typeWhether the result of the REST service is text or binary data. This parameter determines the result type of this operator (document or file).
- json content-typeOnly visible if json is selected as the request body type. The Content-Type sent with the JSON request. Be careful, setting this to a value not expected by the REST endpoint may very well cause the endpoint to not work correctly or even reject the request!
- xml content-typeOnly visible if xml is selected as the request body type. The Content-Type sent with the XML request. Be careful, setting this to a value not expected by the REST endpoint may very well cause the endpoint to not work correctly or even reject the request!
- binary content-typeOnly visible if binary is selected as the request body type. The Content-Type sent with the binary request. Be careful, setting this to a value not expected by the REST endpoint may very well cause the endpoint to not work correctly or even reject the request!
- request headersAdditional headers to include in the request. Can be for example used to log into protected services via an "Authorization" header.
- inject connection secretEnables the injection of a connection secret by replacing the identifier and secret placeholders defined in the selected connection entry with their respective values.
- connection entryThis parameter is only available when inject connection secret is enabled. This parameter is used to specify a repository location that represents a connection entry.
- fail on endpoint errorBy default, if a web service returns an error in the 4xx or 5xx range, this operator will fail. Sometimes however, some requests may be expected to fail, but the process should still continue (and for example return the error in the output document). In those cases, select this checkbox to keep the process going. Note that this operator will still fail if the call fails for technical reasons, e.g. the URL cannot be reached.
Tutorial Processes
POST JSON to a REST service with input document
This process posts JSON (coming from a document) to a REST service and returns the response from it as a document.
POST JSON to a REST service with macro
This process posts JSON (coming from the request json parameter) to a REST service and returns the response from it as a document. The JSON parameter contains two macros which are replaced before the request is sent.
POST form data to a REST service
This process posts form data (coming from the request form parameter) to a REST service and returns the response from it as a document.
